docs(assert/require): clarify allowed rx values for Regexp/NotRegexp (#268, #1793)#1817
docs(assert/require): clarify allowed rx values for Regexp/NotRegexp (#268, #1793)#1817kdt523 wants to merge 5 commits intostretchr:masterfrom
Conversation
Signed-off-by: kdt523 <krushna.datir231@vit.edu>
… checks Signed-off-by: kdt523 <krushna.datir231@vit.edu>
…puts Signed-off-by: kdt523 <krushna.datir231@vit.edu>
…mment line Signed-off-by: kdt523 <krushna.datir231@vit.edu>
|
|
||
| // Lenf asserts that the specified object has specific length. | ||
| // Lenf also fails if the object has a type that len() not accept. | ||
| // Len also fails if the object has a type that len() not accept. |
There was a problem hiding this comment.
This change seems unexpected
There was a problem hiding this comment.
Hi @ccoVeille, thanks for catching that! The comment was updated to clarify that both [Lenf] and [Len] will fail if the object’s type isn’t accepted by Go’s built-in [len()] function. This makes the documentation more explicit for users who might be unsure about which types are supported. If you think the wording could be improved or if it’s redundant, I’m happy to adjust further.
| // Regexp asserts that a specified regexp matches a string. | ||
| // | ||
| // The rx (expression) argument should be a *regexp.Regexp. For backward | ||
| // compatibility, if rx is any other type, its value will be formatted with | ||
| // %v and compiled using regexp.Compile. |
There was a problem hiding this comment.
I would use godoc links
| // Regexp asserts that a specified regexp matches a string. | |
| // | |
| // The rx (expression) argument should be a *regexp.Regexp. For backward | |
| // compatibility, if rx is any other type, its value will be formatted with | |
| // %v and compiled using regexp.Compile. | |
| // Regexp asserts that a specified regexp matches a string. | |
| // | |
| // The rx (expression) argument should be a [*regexp.Regexp]. For backward | |
| // compatibility, if rx is any other type, its value will be formatted with | |
| // %v and compiled using [regexp.Compile]. |
There was a problem hiding this comment.
Thanks for the suggestion, @ccoVeille! I’ve updated the doc comments to use GoDoc link syntax for both [regexp.Regexp] and [regexp.Compile] as you recommended. This should make the documentation clearer and more helpful for users. Let me know if you have any other feedback
|
@a2not Could you give a hand and review this? |
dolmen
added
pkg-assert
a2not
left a comment
a2not
left a comment
There was a problem hiding this comment.
This would not address issues that I want to solve in #1842 , so this PR and #1842 can coexist.
I agree with the other reviews, but they still haven’t been addressed yet.
https://github.com/stretchr/testify/pull/1817/changes#r2471186618
https://github.com/stretchr/testify/pull/1817/changes#r2471191206
| // 3) Append formatted message args at the end of each Namef(...) call within a single line. | ||
| // Use a greedy match until the last closing paren on the same line to avoid inserting inside nested parentheses. | ||
| // Example: Namef(t, uint32(123), int32(123)) -> Namef(t, uint32(123), int32(123), "error message %s", "formatted") | ||
| addArgsLine := regexp.MustCompile(`(?m)` + regexp.QuoteMeta(f.DocInfo.Name+"f(") + `(.*)\)`) |
There was a problem hiding this comment.
This multiline mode (?m) does nothing here, since all of the function call examples are inline.
This can be deleted and would still have the same output from code generation.
| addArgsLine := regexp.MustCompile(`(?m)` + regexp.QuoteMeta(f.DocInfo.Name+"f(") + `(.*)\)`) | |
| addArgsLine := regexp.MustCompile(regexp.QuoteMeta(f.DocInfo.Name+"f(") + `(.*)\)`) |
For the multiline formatting examples, especially EventuallyWithTf, is going to be handled by #1842 .
|
|
||
| // 1) Ensure the leading doc header uses the formatted name (e.g., "Equalf asserts ..."). | ||
| // Only change the very first line that starts with "// <Name>". | ||
| headerPattern := regexp.MustCompile(`^//\s*` + regexp.QuoteMeta(f.DocInfo.Name) + `\b`) |
There was a problem hiding this comment.
You can eliminate this caret to have it replace all of Len to Lenf which is pointed out by this review comment. Besides, * for \s seems unnecessary.
https://github.com/stretchr/testify/pull/1817/changes#r2471186618
| headerPattern := regexp.MustCompile(`^//\s*` + regexp.QuoteMeta(f.DocInfo.Name) + `\b`) | |
| headerPattern := regexp.MustCompile(`//\s` + regexp.QuoteMeta(f.DocInfo.Name) + `\b`) |
| return "// " + strings.Replace(strings.TrimSpace(f.DocInfo.Doc), "\n", "\n// ", -1) | ||
| // Preserve original indentation, but ensure lines that start with a tab are | ||
| // prefixed with "//\t" (no extra space) to match canonical formatting of code examples. | ||
| raw := strings.TrimSpace(f.DocInfo.Doc) | ||
| lines := strings.Split(raw, "\n") | ||
| for i, line := range lines { | ||
| if strings.HasPrefix(line, "\t") { | ||
| // Example/code line: keep the leading tab directly after // | ||
| lines[i] = "//\t" + strings.TrimPrefix(line, "\t") | ||
| } else { | ||
| lines[i] = "// " + line | ||
| } | ||
| } | ||
| return strings.Join(lines, "\n") |
There was a problem hiding this comment.
I don't see the point of changing here. I tried revert this diff and still got the same output from codegen... 🤔
4 participants
docs(assert/require): clarify allowed rx values for Regexp/NotRegexp (#268, #1793)
Summary
Clarify the allowed types and runtime behavior of the rx argument for assert.Regexp, assert.NotRegexp and their require and *f variants. This is a documentation-only change.
Changes
Updated function comments in:
assert/assertions.go
assert/assertion_format.go
assert/assertion_forward.go
require/require.go
require/require_forward.go
The comments now:
State that the preferred rx value is a *regexp.Regexp.
Explain that non-*regexp.Regexp values are stringified and compiled (historical behavior preserved).
Motivation
Users were unclear about which types are accepted for the rx parameter and whether passing a plain string or other value was supported. The code historically accepts interface{} and falls back to stringifying and compiling the value; documenting this explicitly reduces confusion and helps callers choose the safest/most efficient usage (passing a compiled *regexp.Regexp when possible).
Related issues
#1793
Behavior / Tests
Behavior: No runtime or API behavior changes were made. The implementation still stringifies non-*regexp.Regexp values and compiles them with regexp.MustCompile (same as before). This PR is documentation-only.
Tests: I ran package tests for the changed packages locally:
go test ./assert ./require — passed.
Note: Running go test d:. on Windows may show failures in suite due to environment-specific tests (panic/restart tests and -race subprocess builds needing a C toolchain). Those failures are unrelated to this docs-only change.